Перейти к основному содержимому
Версия: 2.0

Фиды

Методы API получения фидов

Важно!

Структура фидов описана в разделе Справочники.

GET /api/v2/feeds/tree​

Метод используется для получения дерева доступных для клиента фидов с учетом иерархии.
Выводятся не все, а только доступные для клиента фиды.
Вызывается без параметров.

Пример запроса​

curl --location --request GET 'https://api.data.rt-solar.ru/api/v2/feeds/tree' \
--header 'Authorization: Bearer {JWT_TOKEN}'

Пример ответа​

В ответе API будет предоставлен список фидов в массиве feeds представленный в древовидной структуре.

{
    "feeds": [
        {
            "name": "4rays_pulse",
            "id": "111306d9-87ea-4027-b865-ad6dfaa70abc",
            "feeds": [
                {
                    "name": "active_c2",
                    "id": "222306d9-87ea-4027-b865-ad6dfaa70abc",
                    "parent_id": "111306d9-87ea-4027-b865-ad6dfaa70abc"
                },
                {
                    "name": "cybercrime",
                    "id": "333306d9-87ea-4027-b865-ad6dfaa70abc",
                    "parent_id": "111306d9-87ea-4027-b865-ad6dfaa70abc",
                    "feeds": [
                        {
                            "name": "honeypot_attacker",
                            "id": "444306d9-87ea-4027-b865-ad6dfaa70abc",
                            "parent_id": "333306d9-87ea-4027-b865-ad6dfaa70abc"
                        }
                    ]
                }
            ]
        },
        {
            "name": "generic",
            "id": "555306d9-87ea-4027-b865-ad6dfaa70abc",
            "feeds": [
                {
                    "name": "apt",
                    "id": "666306d9-87ea-4027-b865-ad6dfaa70abc",
                    "parent_id": "555306d9-87ea-4027-b865-ad6dfaa70abc"
                }
            ]
        },
        {
            "name": "fincert",
            "id": "777306d9-87ea-4027-b865-ad6dfaa70abc"
        }
    ]
}

Описание ответа​

В ответе API представляются данные в формате JSON.

№ПолеТип данныхОписаниеПример
1namestringНазвание фида"name": "active_c2"
2idstringUUID фида"id": "421da453-5f3b-4542-b8fe-099f7d9cbe2b"
3feedsarray(string)Массив дочерних фидов. Заполняется только для дочерних фидов
{
"feeds": [
  {
    "name": "generic", 
    "id": "555306d9-87ea-4027-b865-ad6dfaa70abc", 
    "feeds": [
      {
        "name": "apt", 
        "id": "666306d9-87ea-4027-b865-ad6dfaa70abc", 
        "parent_id": "555306d9-87ea-4027-b865-ad6dfaa70abc"
      }
    ]
  }
]
}
4parent_idstringUUID родительского фида. Заполняется только для дочерних фидов"parent_id": "421da453-5f3b-4542-b8fe-099f7d9cbe2b"

GET /api/v2/feeds/{feed-name-by-tree}​

Метод используется для получения индикаторов конкретного фида.
В параметре feed-name-by-tree передается название фида (пути, источники данных), из которого запрашиваются индикаторы.

Примеры параметра feed-name-by-tree
  • /4rays_pulse
  • /4rays_pulse/active_c2
  • /4rays_pulse/cybercrime
  • /4rays_pulse/cybercrime/backdoor

При вызове метода API GET /api/v2/feeds без параметров вернутся все индикаторы из доступных пользователю фидов.

Пример запроса​

curl --location --request GET 'https://api.data.rt-solar.ru/api/v2/feeds/4rays_pulse' \
--header 'Authorization: Bearer {JWT_TOKEN}'

Пример запроса без параметров​

curl --location --request GET 'https://api.data.rt-solar.ru/api/v2/feeds' \
--header 'Authorization: Bearer {JWT_TOKEN}'

Параметры запроса​

№ПараметрТип данныхОбязательностьОписаниеВарианты значений
1updated_atstringнет
  1. В данном параметре передается дата и время (с указанием микросекунд) создания или обновления индикатора в формате ISO с точностью до микросекунд
  2. Если значение параметра отсутствует, то поиск будет производиться по всем индикаторам без фильтрации по времени
  3. Если параметр указан, запрос вернёт не более limit индикаторов, отсортированных в порядке, заданном в direction_sort
  • При direction_sort=ASC будут выбраны индикаторы, чья дата создания или обновления больше указанного значения (от старых к новым)
  • При direction_sort=DESC будут выбраны индикаторы, чья дата создания или обновления меньше указанного значения (от новых к старым)
2022-10-26T17:30:00.000001Z
2actionsstringнет
  1. В данном параметре передается состояние индикатора, который нужно вернуть в ответе
  2. Если значение отсутствует, то поиск будет производиться по всем полям
  3. При передаче параметра может быть указано несколько значений через запятую

Допустимые значения:

  • CREATE
  • UPDATE
  • DELETE
3fieldsstringнет
  1. В данном параметре передается список полей, которые вернутся в ответе
  2. Если значение отсутствует, то поиск будет производиться по всем полям
  3. При передаче параметра может быть указано несколько значений через запятую
  4. Если в запросе в параметре fields передано невалидное значение, то будет возвращена ошибка с кодом 400. Обязательные значения ответа: updated_at

Допустимые значения:

  • id
  • type
  • value
  • description
  • created_at
  • updated_at
  • first_seen
  • last_seen
  • zone
  • categories
  • feeds
  • attributes
  • contexts
  • related_objects
  • network
  • file
  • cve
4limitintнетДанный параметр ограничивает число записей, которые возвращаются в ответе. Значение по умолчанию - 100, максимальное значение - 1000100
5direction_sortstringнетЗадает направление сортировки и итерации. При ASC порядок индикаторов в ответе отсортирован по возрастанию, при DESC - по убыванию (от новых к старым).

Допустимые значения:

  • ASC
  • DESC
6indicator_typesarray(string)да

Типы индикатора

Допустимые значения:

  • IPV4
  • SOCKETV4
  • IPV6
  • SOCKETV6
  • URL
  • DOMAIN
  • MD5
  • SHA1
  • SHA256

Пример ответа​

API возвращает массив объектов, каждый из которых содержит полную информацию об индикаторе компрометации (IoC). Ниже представлен пример одного элемента массива с подробными комментариями к ключевым полям:

[
  {
  "id": "421da453-5f3b-4542-b8fe-099f7d9cbe2b",
  "type": "IPV4",
  "value": "192.0.2.100",
  "description": "описание",
  "created_at": "2022-10-26T17:30:00.000001Z",
  "updated_at": "2022-10-26T17:30:00.000001Z",
  "first_seen": "2022-10-26T17:30:00.000001Z",
  "last_seen": "2022-10-26T17:30:00.000001Z",
  "zone": "MALICIOUS",
  "cve": "CVE-2021-44228, CVE-2018-20580",
  "categories": [
    "malicious"
  ],
  "feeds": [
    {
      "name": "4rays_pulse",
      "action": "create",
      "valid_until": "2022-10-26T17:30:00.000001Z",
      "feeds": [
        {
          "name": "c2",
          "action": "create",
          "valid_until": "2025-10-26T17:30:00.000001Z"
        }
      ]
    }
  ],
  "attributes": {
    "key": "value"
  },
  "contexts": [
    {
      "source_name": "whois",
      "attributes": {
        "nameservers": "ns1.example-domain.net",
        "registrar": "EXAMPLE-REGISTRAR-RU"       
      }
    }
  ],
  "related_objects": [
    {
      "id": "cf830e6d-addc-4983-8c38-906ef5fb6457",
      "type": "IPV4",
      "value": "203.0.113.50"
    },
    {
      "id": "12330e6d-addc-4983-8c38-906ef5fb6457",
      "type": "threat_actor",
      "value": "Example Threat Actor",
      "ttps": [
        {
            "mitre_id": "T1134",
            "mitre_url": "https://attack.mitre.org/techniques/T1134/"
        },
        {
            "mitre_id": "T1134.001",
            "mitre_url": "https://attack.mitre.org/techniques/T1134/001/"
        }
    ]
    }  
  ],
  "network": {
    "heuristics": [
      {
        "risk_level": "CRITICAL",
        "description": "У индикатора обнаружены признаки вредоносной активности, соответствующей его категории"
      }
    ]
  },
  "file": {
    "verdicts": ["YARA:Nix.HackTool.3snake.1a"],
    "os": "Nix",
    "size": 207232,
    "file_identifiers": ["php-fpm"],
    "mime": "application/x-sharedlib",
    "malware_family": ["nix.hacktool.3snake.1a"],
    "hashes": {
      "md5": "d41d8cd98f00b204e9800998ecf8427e",
      "sha1": "da39a3ee5e6b4b0d3255bfef95601890afd80709"
    }
  }
},
{
  "..."
}
]

Описание ответа​

В ответе API предоставляется массив объектов в формате JSON.

№ПолеТип данныхОписаниеВарианты значенийПример
1idstringUUID индикатора-"id": "421da453-5f3b-4542-b8fe-099f7d9cbe2b"
2typestringТип индикатора

IPV4, IPV6, SOCKETV4, SOCKETV6, URL, DOMAIN, MD5, SHA1, SHA256

"type": "IPV4"
3valuestringЗначение индикатора-"value": "5.8.95.174"
4descriptionstringОписание индикатора-"description": "IP dangerous"
5created_atstringДата и время создания индикатора-"created_at": "2022-10-26T17:30:00.000001Z"
6updated_atstringДата и время совершения изменений для индикатора-"updated_at": "2022-10-26T17:30:00.000001Z"
7first_seenstringДата и время первого обнаружения индикатора-"first_seen": "2022-10-26T17:30:00.000001Z"
8last_seenstringДата и время последнего обнаружения индикатора-"last_seen": "2022-10-26T17:30:00.000001Z"
9zonestringОпределяет уровень критичности угрозы и позволяет классифицировать индикаторы по степени потенциальной опасности.

Описание поля zone

"zone": "MALICIOUS"
10categoriesarray (string)Категории индикатора

Примеры: malicious, spam,
phishing, c2, malware, etc.

"categories": ["spam"]
11feedsarray (object)

Массив объектов с информацией о фидах. Каждый объект содержит:

  • name - название фида
  • action - действие
  • valid_until - срок валидности индикатора
  • feeds - вложенный массив фидов

CREATE, UPDATE, DELETE

{
"feeds": [
  {
    "name": "4rays_pulse", 
    "action": "create", 
    "valid_until": "2022-10-26T17:30:00.000001Z", 
    "feeds": [
      {
        "name": "c2", 
        "action": "create", 
        "valid_until": "2022-10-26T17:30:00.000001Z"
      }
    ]
  }
]
}
12attributesobjectДополнительные атрибуты индикатора в формате ключ-значениеСодержит произвольные пары ключ-значение для хранения дополнительной информации"attributes": {"key": "value"}
13contextsarray (object)

Контекстная информация об индикаторе из различных источников. Каждый объект содержит:

  • source_name - название источника
  • attributes - атрибуты контекста

Описание источников и их атрибутов

"contexts": [
{
  "source_name": "whois",
  "attributes": {
    "nameservers": "ns1.timeweb.org",
    "registrar": "RU-CENTER-RU"
  }
},
{
  "source_name": "ipapi",
  "attributes": {
    "hosting_facility": "Example Hosting",
    "isp": "Example ISP",
    "asn": "AS12345"
  }
}
]
14related_objectsarray (object)

Массив связанных объектов с их идентификаторами, типами и значениями. Каждый объект содержит:
• id:
UUID связанного объекта
• type:
тип связанного объекта
• value:
значение связанного объекта

Объект типа threat_actor так же может содержать дополнительное поле ttps - связанные тактики, техники и процедуры (TTPs)

"related_objects": [
  {
    "id": "cf830e6d-addc-4983-8c38-906ef5fb6457",
    "type": "IPV4",
    "value": "95.119.184.232"
  },
  {
    "id": "12330e6d-addc-4983-8c38-906ef5fb6457",
    "type": "threat_actor",
    "value": "Shedding Zmiy",
    "ttps": [
      {
        "mitre_id": "T1134",
        "mitre_url": "https://attack.mitre.org/techniques/T1134/"
      },
      {
        "mitre_id": "T1134.001",
        "mitre_url": "https://attack.mitre.org/techniques/T1134/001/"
      }
    ]
  }
]
15networkobject

Сетевая информация об индикаторе.

Описание поля heuristics

{
"network": {
  "heuristics": [
    {
      "risk_level": "HIGH", 
      "description": "Suspicious Network Behavior - обнаружены множественные подключения к недоверенным хостам в короткий промежуток времени"
    }
  ]
}
}
16fileobject

Информация о файле (для файловых индикаторов).

Описание поля file

{
"file": {
  "verdicts": ["YARA:Nix.HackTool.3snake.1a"],
  "os": "Nix",
  "size": 207232,
  "file_identifiers": ["php-fpm"],
  "mime": "application/x-sharedlib",
  "malware_family": ["nix.hacktool.3snake.1a"],
  "hashes": {
    "md5": "11160afc0a8606b67c1eec4c39fd94fe",
    "sha1": "111d7440595261b4ecfe43d797a6a06a3a5654f4"
  }
}
}
17cvearray(string)Связанные с индикатором уязвимости-"cve": ["CVE-2021-44228", "CVE-2018-20580"]

Контекстная информация об индикаторе из различных источников​

Это необязательный набор данных, который может присутствовать для обогащения индикаторов дополнительными сведениями.

Каждый объект контекста contexts содержит:

  • source_name - название источника данных
  • attributes - атрибуты контекста в формате ключ-значение

Возможные источники source_name и их атрибуты attributes:

1. Источник: ipapi

  • hosting_facility - хостинг-провайдер
  • is_tor - является ли TOR-нодой
  • is_crawler - является ли сканирующим сервисом
  • is_proxy - является ли прокси-сервисом
  • isp - интернет-провайдер
  • asn - номер автономной системы
  • country - геопозиция хоста

2. Источник: whois

  • nameservers - DNS-серверы домена
  • creation - дата создания домена
  • expiration - дата истечения регистрации домена
  • registrar - регистратор домена

3. Источник: fstec

  • id - идентификатор записи
  • date - дата публикации информации
  • summary - краткое описание, содержащее номер бюллетеня
Важно:

Наличие конкретных источников и атрибутов зависит от типа индикатора и доступности данных в момент обогащения.

Описание поля heuristics​

Эвристика - результирующее правило или алгоритм, который на основе анализа данных и признаков формирует вероятностную оценку или классификацию объекта/события.
Результат работы эвристики:
Результатом работы эвристики является автоматически сгенерированное заключение, которое:

  • Классифицирует объект по уровням риска, на основе которых определяется зона
  • Формулирует текстовое описание выявленных признаков и рисков

Пример:

"heuristics": [
{
  "risk_level": "HIGH",
  "description": "Suspicious Network Behavior - обнаружены множественные подключения к недоверенным хостам в короткий промежуток времени"
}
]
№ПолеТип данныхОписаниеДопустимые значенияПример
1risk_levelstringУровень риска
  • CRITICAL
  • HIGH
  • MEDIUM
  • DECREASE
  • SAFE
  • INFO
"risk_level": "CRITICAL"
2descriptionstringОписание эвристики-"description": "Обнаружена подозрительная сетевая активность"

Описание поля file​

№ПолеТип данныхОписаниеПример
1verdictsarray(string)Вердикт анализа файла

"verdicts": ["Cross.Dangerous.4RAYS.1a"]

2osstringЦелевая операционная система, может принимать следующие значения: WIN, NIX, MAC, CROSS, ANDROID"os": "WIN"
3sizeintРазмер файла"size": 207232
4file_identifiersarray(string)Имена и пути файла"file_identifiers": ["errorFE.png"]
5mimestringMIME-тип файла"mime": "application/x-dosexec"
6malware_familyarray(string)Информация о вредоносности"malware_family": ["antspy", "obstinate_mogwai_group"]
7hashesobject

Объект в котором содержатся недостающие хеши файла (при наличии файла). Допустимые значения:

  • md5
  • sha1
  • sha256
{
"hashes": {
  "md5": "d41d8cd98f00b204e9800998ecf8427e", 
  "sha1": "da39a3ee5e6b4b0d3255bfef95601890afd80709"
}
}

или

{
"hashes": {
  "md5": "d41d8cd98f00b204e9800998ecf8427e", 
  "sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
}
}